<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Tutorial metadata &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="“Per-method” tutorials" href="per-method-tutorial.html" />
    <link rel="prev" title="Markdown processing within tutorials" href="tutorial-markdown.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="tutorial-metadata">
<h1>Tutorial metadata<a class="headerlink" href="#tutorial-metadata" title="Link to this heading">¶</a></h1>
<p>At the moment, the tutorials are represented as a list. However, this
configuration will get difficult to navigate once the number of
provided tutorials will grow.  Therefore, we want to include the
possibility to filter the tutorials thanks to tags, such as the
difficulty level of the tutorial for example. This will allow an
easier navigation for the user.</p>
<section id="representation-in-the-code">
<h2>Representation in the code<a class="headerlink" href="#representation-in-the-code" title="Link to this heading">¶</a></h2>
<p>The data is saved in the file <code class="docutils literal notranslate"><span class="pre">metadata.json</span></code>. Such files can be
found in each tutorial directory.  The top-level entity is an object,
whose JSON representation is as follows:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>{&quot;name_of_tag&quot;: &quot;value_of_tag&quot;}
</pre></div>
</div>
<p>At the moment, the only tags used are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">difficulty</span></code> — what level of challenge the tutorial presents;
currently one of the strings <code class="docutils literal notranslate"><span class="pre">&quot;getting</span> <span class="pre">started&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;beginner&quot;</span></code>,
<code class="docutils literal notranslate"><span class="pre">&quot;medium&quot;</span></code>, and <code class="docutils literal notranslate"><span class="pre">&quot;advanced&quot;</span></code>;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">programKind</span></code> — what representation of a Pytch program does the
tutorial work with; currently one of the strings <code class="docutils literal notranslate"><span class="pre">&quot;flat&quot;</span></code> and
<code class="docutils literal notranslate"><span class="pre">&quot;per-method&quot;</span></code>; can be omitted, in which case <code class="docutils literal notranslate"><span class="pre">&quot;flat&quot;</span></code> is
assumed; the strings here match the values of the type
<code class="docutils literal notranslate"><span class="pre">PytchProgram[&quot;kind&quot;]</span></code> in the TypeScript front end.</p></li>
</ul>
<p>The property <code class="docutils literal notranslate"><span class="pre">metadata_text()</span></code> of the <code class="docutils literal notranslate"><span class="pre">ProjectHistory</span> <span class="pre">class</span></code> reads
the content of the <code class="docutils literal notranslate"><span class="pre">metadata.json</span></code> files, from the last tip-commit
or from the working directory.  Then the property
<code class="docutils literal notranslate"><span class="pre">summary_div_from_project_history()</span></code> adds an HTML attribute called
<code class="docutils literal notranslate"><span class="pre">data-metadata-json</span></code> to the <code class="docutils literal notranslate"><span class="pre">summary_div</span></code> object. The content of
that attribute will be the <code class="docutils literal notranslate"><span class="pre">metadata_text</span></code> property.  This is an
example of what can be found in the <code class="docutils literal notranslate"><span class="pre">summary.html</span></code> file:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;tutorial-summary&quot;</span> <span class="na">data-metadata-json</span><span class="o">=</span><span class="s">&#39;{&quot;difficulty&quot;: &quot;advanced&quot;}&#39;</span><span class="p">&gt;</span>
<span class="cm">&lt;!-- tutorial content --&gt;</span>
<span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Each individual tutorial’s metadata is also provided as the attribute
<code class="docutils literal notranslate"><span class="pre">data-metadata-json</span></code> in the top-level <cite>div</cite>.</p>
</section>
<section id="representation-in-the-output">
<h2>Representation in the output<a class="headerlink" href="#representation-in-the-output" title="Link to this heading">¶</a></h2>
<p>In the front end, the work of processing the HTML of each tutorial’s
<code class="docutils literal notranslate"><span class="pre">summary_div</span></code> is done in the <code class="docutils literal notranslate"><span class="pre">&lt;TutorialSummaryDisplay&gt;</span></code> component.
The parsed metadata object is stored in a slot <code class="docutils literal notranslate"><span class="pre">metadata:</span> <span class="pre">any</span></code>
within the type <code class="docutils literal notranslate"><span class="pre">ITutorialSummary</span></code>.  The function
<code class="docutils literal notranslate"><span class="pre">allTutorialSummaries()</span></code> in <code class="docutils literal notranslate"><span class="pre">src/database/tutorials.ts</span></code> pulls out
the JSON metadata from the attribute, parses it, and uses the result
as the value of the metadata slot.  Finally, in the
<code class="docutils literal notranslate"><span class="pre">&lt;TutorialSummaryDisplay&gt;</span></code>, we use <code class="docutils literal notranslate"><span class="pre">tutorial.metadata</span></code> to look for
a “difficulty” property, and insert a suitable <code class="docutils literal notranslate"><span class="pre">&lt;div&gt;</span></code> to show it on
screen.</p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../vm/user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../vm/developer/index.html">VM</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Tools</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../index.html#tutorial-compiler-and-related-tools">Tutorial compiler and related tools</a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#assembly-of-website-bundle">Assembly of website bundle</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>